home *** CD-ROM | disk | FTP | other *** search
/ The CICA Windows Explosion! / The CICA Windows Explosion! - Disc 2.iso / demo / wemdemo4.zip / INFO / ELISP.17 < prev    next >
Text File  |  1994-09-21  |  50KB  |  1,234 lines
  1. Info file elisp, produced by Makeinfo, -*- Text -*- from input file
  2. elisp.texi.
  3.  
  4.    This file documents GNU Emacs Lisp.
  5.  
  6.    This is edition 1.03 of the GNU Emacs Lisp Reference Manual,   for
  7. Emacs Version 18.
  8.  
  9.    Published by the Free Software Foundation, 675 Massachusetts
  10. Avenue,  Cambridge, MA 02139 USA
  11.  
  12.    Copyright (C) 1990 Free Software Foundation, Inc.
  13.  
  14.    Permission is granted to make and distribute verbatim copies of
  15. this manual provided the copyright notice and this permission notice
  16. are preserved on all copies.
  17.  
  18.    Permission is granted to copy and distribute modified versions of
  19. this manual under the conditions for verbatim copying, provided that
  20. the entire resulting derived work is distributed under the terms of a
  21. permission notice identical to this one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that this permission notice may be stated in a
  26. translation approved by the Foundation.
  27.  
  28.  
  29. 
  30. File: elisp,  Node: Word Motion,  Next: Buffer End Motion,  Prev: Character Motion,  Up: Motion
  31.  
  32. Motion by Words
  33. ---------------
  34.  
  35.    These functions for parsing words use the syntax table to decide
  36. whether a given character is part of a word.  *Note Syntax Tables::.
  37.  
  38.  * Command: forward-word COUNT
  39.      This function moves point forward COUNT words (or backward if
  40.      COUNT is negative).  Normally it returns `t'.  If this motion
  41.      encounters the beginning or end of the buffer, or the limits of
  42.      the accessible portion when narrowing is in effect, point stops
  43.      there and the value is `nil'.
  44.  
  45.      In an interactive call, COUNT is set to the numeric prefix
  46.      argument.
  47.  
  48.  * Command: backward-word COUNT
  49.      This function just like `forward-word', except that it moves
  50.      backward until encountering the front of a word, rather than
  51.      forward.
  52.  
  53.      In an interactive call, COUNT is set to the numeric prefix
  54.      argument.
  55.  
  56.      This function is rarely used in programs, as it is more
  57.      efficient to call `forward-word' with negative argument.
  58.  
  59.  
  60. 
  61. File: elisp,  Node: Buffer End Motion,  Next: Text Lines,  Prev: Word Motion,  Up: Motion
  62.  
  63. Motion to an End of the Buffer
  64. ------------------------------
  65.  
  66.    To move point to the beginning of the buffer, write:
  67.  
  68.      (goto-char (point-min))
  69.  
  70. Likewise, to move to the end of the buffer, use:
  71.  
  72.      (goto-char (point-max))
  73.  
  74.    Here are two commands which users use to do these things.  They
  75. are documented here to warn you not to use them in Lisp programs,
  76. because they set the mark and display messages in the echo area.
  77.  
  78.  * Command: beginning-of-buffer &optional N
  79.      This function moves point to the beginning of the buffer (or the
  80.      limits of the accessible portion, when narrowing is in effect),
  81.      setting the mark at the previous position.  If N is non-`nil',
  82.      then it puts point N tenths of the way from the beginning of the
  83.      buffer.
  84.  
  85.      In an interactive call, N is the numeric prefix argument, if
  86.      provided; otherwise N defaults to `nil'.
  87.  
  88.      Don't use this function in Lisp programs!
  89.  
  90.  * Command: end-of-buffer &optional N
  91.      This function moves point to the end of the buffer (or the
  92.      limits of the accessible portion, when narrowing is in effect),
  93.      setting the mark at the previous position.  If N is non-`nil',
  94.      then it puts point N tenths of the way from the end.
  95.  
  96.      In an interactive call, N is the numeric prefix argument, if
  97.      provided; otherwise N defaults to `nil'.
  98.  
  99.      Don't use this function in Lisp programs!
  100.  
  101.  
  102. 
  103. File: elisp,  Node: Text Lines,  Next: Screen Lines,  Prev: Buffer End Motion,  Up: Motion
  104.  
  105. Motion by Text Lines
  106. --------------------
  107.  
  108.    Text lines are portions of the buffer delimited by newline
  109. characters, which are regarded as part of the previous line.  The
  110. first text line begins at the beginning of the buffer, and the last
  111. text line ends at the end of the buffer whether or not the last
  112. character is a newline.  The division of the buffer into text lines
  113. is not affected by the width of the window, or by how tabs and
  114. control characters are displayed.
  115.  
  116.  * Command: goto-line LINE
  117.      This function moves point to the front of the LINEth line,
  118.      counting from line 1 at beginning of buffer.  If LINE is less
  119.      than 1, then point is set to the beginning of the buffer.  If
  120.      LINE is greater than the number of lines in the buffer, then
  121.      point is set to the *end of the last line* of the buffer.
  122.  
  123.      If narrowing is in effect, then LINE still counts from the
  124.      beginning of the buffer, but point cannot go outside the
  125.      accessible portion.  So point is set at the beginning or end of
  126.      the accessible portion of the text if the line number specifies
  127.      a position that is inaccessible.
  128.  
  129.      The return value of `goto-line' is the difference between LINE
  130.      and the line number of the line to which point actually was able
  131.      move (before taking account of any narrowing).  Thus, the value
  132.      is positive if the scan encounters the end of the buffer.
  133.  
  134.      In an interactive call, LINE is the numeric prefix argument if
  135.      one has been provided.  Otherwise LINE is read in the minibuffer.
  136.  
  137.  * Command: beginning-of-line &optional COUNT
  138.      This function moves point to the beginning of the current line. 
  139.      With an argument COUNT not `nil' or 1, it moves forward COUNT-1
  140.      lines and then to the beginning of the line.
  141.  
  142.      If this function reaches the end of the buffer (or of the
  143.      accessible portion, if narrowing is in effect), it positions
  144.      point at the beginning of the last line.  No error is signaled.
  145.  
  146.  * Command: end-of-line &optional COUNT
  147.      This function moves point to the end of the current line.  With
  148.      an argument COUNT not `nil' or 1, it moves forward COUNT-1 lines
  149.      and then to the end of the line.
  150.  
  151.      If this function reaches the end of the buffer (or of the
  152.      accessible portion, if narrowing is in effect), it positions
  153.      point at the end of the last line.  No error is signaled.
  154.  
  155.  * Command: forward-line &optional COUNT
  156.      This function moves point forward COUNT lines, to the beginning
  157.      of the line.  If COUNT is negative, it moves point -COUNT lines
  158.      backward, to the beginning of the line.
  159.  
  160.      If the beginning or end of the buffer (or of the accessible
  161.      portion) is encountered before that many lines are found, then
  162.      point stops at the beginning or end.  No error is signaled.
  163.  
  164.      `forward-line' returns the difference between COUNT and the
  165.      number of lines actually moved.  If you attempt to move down
  166.      five lines from the beginning of a buffer that has only three
  167.      lines, point will positioned at the end of the last line, and
  168.      the value will be 2.
  169.  
  170.      In an interactive call, COUNT is the numeric prefix argument.
  171.  
  172.  * Function: count-lines START END
  173.      This function returns the number of lines between the positions
  174.      START and END in the current buffer.  If START and END are
  175.      equal, then it returns 0.  Otherwise it returns at least 1, even
  176.      if START and END are on the same line.  This is because the text
  177.      between them, considered in isolation, must contain at least one
  178.      line unless it is empty.
  179.  
  180.      Here is an example of using `count-lines':
  181.  
  182.           (defun current-line ()
  183.             "Return the vertical position of point in the selected window.  
  184.           Top line is 0.  Counts each text line only once, even if it wraps."
  185.             (+ (count-lines (window-start) (point))
  186.                (if (= (current-column) 0) 1 0)
  187.                -1))
  188.  
  189.    Also see the functions `bolp' and `eolp' in *Note Near Point::. 
  190. These functions do not move point, but test whether it is already at
  191. the beginning or end of a line.
  192.  
  193.  
  194. 
  195. File: elisp,  Node: Screen Lines,  Next: Vertical Motion,  Prev: Text Lines,  Up: Motion
  196.  
  197. Motion by Screen Lines
  198. ----------------------
  199.  
  200.    The line functions in the previous section count text lines,
  201. delimited only by newline characters.  By contrast, these functions
  202. count screen lines, which are defined by the way the text appears on
  203. the screen.  A text line is a single screen line if it is short
  204. enough to fit the width of the selected window, but otherwise it may
  205. occupy several screen lines.
  206.  
  207.    In some cases, text lines are truncated on the screen rather than
  208. continued onto additional screen lines.  Then `vertical-motion' moves
  209. point just like `forward-line'.  *Note Truncation::.
  210.  
  211.    Because the width of a given string depends on the flags which
  212. control the appearance of certain characters, `vertical-motion' will
  213. behave differently on a given piece of text found in different
  214. buffers.  It will even act differently in different windows showing
  215. the same buffer, because the width may differ and so may the
  216. truncation flag.  *Note Control Char Display::.
  217.  
  218.  * Function: vertical-motion COUNT
  219.      This function moves point to the start of the screen line COUNT
  220.      screen lines down from the screen line containing point.  If
  221.      COUNT is negative, it moves up instead.
  222.  
  223.      This function returns the number of lines moved.  The value may
  224.      be less in absolute value than COUNT if the beginning or end of
  225.      the buffer was reached.
  226.  
  227.  * Command: move-to-window-line COUNT
  228.      This function moves point with respect to the text currently
  229.      displayed in the selected window.  Point is moved to the
  230.      beginning of the screen line COUNT screen lines from the top of
  231.      the window.  If COUNT is negative, point moves either to the
  232.      beginning of the line -COUNT lines from the bottom or else to
  233.      the last line of the buffer if the buffer ends above the
  234.      specified screen position.
  235.  
  236.      If COUNT is `nil', then point moves to the beginning of the line
  237.      in the middle of the window.  If the absolute value of COUNT is
  238.      greater than the size of the window, then point moves to the
  239.      place which would appear on that screen line if the window were
  240.      tall enough.  This will probably cause the next redisplay to
  241.      scroll to bring that location onto the screen.
  242.  
  243.      In an interactive call, COUNT is the numeric prefix argument.
  244.  
  245.      The value returned is the window line number, with the top line
  246.      in the window numbered 0.
  247.  
  248.  
  249. 
  250. File: elisp,  Node: Vertical Motion,  Next: List Motion,  Prev: Screen Lines,  Up: Motion
  251.  
  252. The User-Level Vertical Motion Commands
  253. ---------------------------------------
  254.  
  255.    A goal column is useful if you want to edit text such as a table
  256. in which you want to move point to a certain column on each line. 
  257. The goal column affects the vertical text line motion commands,
  258. `next-line' and `previous-line'.  *Note : (emacs)Basic.
  259.  
  260.  * User Option: goal-column
  261.      This variable holds an explicitly specified goal column for
  262.      vertical line motion commands.  If it is an integer, it
  263.      specifies a column, and these commands try to move to that
  264.      column on each line.  If it is `nil', then the commands set
  265.      their own goal columns.  Any other value is invalid.
  266.  
  267.  * Variable: temporary-goal-column
  268.      This variable holds the temporary goal column during a sequence
  269.      of consecutive vertical line motion commands.  It is overridden
  270.      by `goal-column' if that is non-`nil'.  It is set each time a
  271.      vertical motion command is invoked, unless the previous command
  272.      was also a vertical motion command.
  273.  
  274.  * User Option: track-eol
  275.      This variable controls how the vertical line motion commands
  276.      operate when starting at the end of a line.  If `track-eol' is
  277.      non-`nil', then vertical motion starting at the end of a line
  278.      will keep to the ends of lines.  This means moving to the end of
  279.      each line moved onto.  The value of `track-eol' has no effect if
  280.      point is not at the end of a line when the first vertical motion
  281.      command is given.
  282.  
  283.      `track-eol' has its effect by causing `temporary-goal-column' to
  284.      be set to 9999 instead of to the current column.
  285.  
  286.  * Command: set-goal-column UNSET
  287.      This command sets the variable `goal-column' to specify a
  288.      permanent goal column for the vertical line motion commands.  If
  289.      UNSET is `nil', then `goal-column' is set to the current column
  290.      of point.  If UNSET is non-`nil', then `goal-column' is set to
  291.      `nil'.
  292.  
  293.      This function is intended for interactive use; and in an
  294.      interactive call, UNSET is the raw prefix argument.
  295.  
  296.  
  297. 
  298. File: elisp,  Node: List Motion,  Next: Skipping Characters,  Prev: Vertical Motion,  Up: Motion
  299.  
  300. Moving over Lists and Other Balanced Expressions
  301. ------------------------------------------------
  302.  
  303.    Here are several functions concerned with balanced-parenthesis
  304. expressions (also called "sexps" in connection with moving across
  305. them in Emacs).  The syntax table controls how these functions
  306. interpret various characters; see *Note Syntax Tables::.  *Note
  307. Parsing Expressions::, for lower-level primitives for scanning sexps
  308. or parts of sexps.  For user-level commands, see *Note : (emacs)Lists
  309. and Sexps.
  310.  
  311.  * Command: forward-list ARG
  312.      Move forward across ARG balanced groups of parentheses.  (Other
  313.      syntatic entities such as words or paired string quotes are
  314.      ignored.)
  315.  
  316.  * Command: backward-list ARG
  317.      Move backward across ARG balanced groups of parentheses.  (Other
  318.      syntatic entities such as words or paired string quotes are
  319.      ignored.)
  320.  
  321.  * Command: up-list ARG
  322.      Move forward out of ARG levels of parentheses.  A negative
  323.      argument means move backward but still to a less deep spot.
  324.  
  325.  * Command: down-list ARG
  326.      Move forward down ARG levels of parentheses.  A negative
  327.      argument means move backward but still go down ARG level.
  328.  
  329.  * Command: forward-sexp ARG
  330.      Move forward across ARG balanced expressions.  Balanced
  331.      expressions include both those delimited by parentheses and
  332.      other kinds, such as words and string constants.  For example,
  333.  
  334.           ---------- Buffer: foo ----------
  335.           (concat-!- "foo " (car x) y z)
  336.           ---------- Buffer: foo ----------
  337.           
  338.           (forward-sexp 3)
  339.                => nil
  340.           
  341.           ---------- Buffer: foo ----------
  342.           (concat "foo " (car x) y-!- z)
  343.           ---------- Buffer: foo ----------
  344.  
  345.  * Command: backward-sexp ARG
  346.      Move backward across ARG balanced expressions.
  347.  
  348.  
  349. 
  350. File: elisp,  Node: Skipping Characters,  Prev: List Motion,  Up: Motion
  351.  
  352. Skipping Characters
  353. -------------------
  354.  
  355.    The following two functions move point over a specified set of
  356. characters.  For example, they are often used to skip whitespace.
  357.  
  358.  * Function: skip-chars-forward CHARACTER-SET &optional LIMIT
  359.      This function moves point in the current buffer forward,
  360.      skipping over a given set of characters.  Emacs first examines
  361.      the character following point; if it matches CHARACTER-SET, then
  362.      point is advanced and the next character is examined.  This
  363.      continues until a character is found that does not match.  The
  364.      function returns `nil'.
  365.  
  366.      The argument CHARACTER-SET is like the inside of a `[...]' in a
  367.      regular expression except that `]' is never special and `\'
  368.      quotes `^', `-' or `\'.  Thus, `"a-zA-Z"' skips over all
  369.      letters, stopping before the first nonletter, and `"^a-zA-Z'"
  370.      skips nonletters stopping before the first letter.  *Note
  371.      Regular Expressions::.
  372.  
  373.      If LIMIT is supplied (it must be a number or a marker), it
  374.      specifies the maximum position in the buffer that point can be
  375.      skipped to.  Point will stop at or before LIMIT.
  376.  
  377.      In the following example, point is initially located directly
  378.      before the `T'.  After the form is evaluated, point is located
  379.      at the end of that line (between the `t' of `hat' and the
  380.      newline).  The function skips all letters and spaces, but not
  381.      newlines.
  382.  
  383.           ---------- Buffer: foo ----------
  384.           I read "-!-The cat in the hat
  385.           comes back" twice.
  386.           ---------- Buffer: foo ----------
  387.           
  388.           (skip-chars-forward "a-zA-Z ")
  389.                => nil
  390.           
  391.           ---------- Buffer: foo ----------
  392.           I read "The cat in the hat-!-
  393.           comes back" twice.
  394.           ---------- Buffer: foo ----------
  395.  
  396.  * Function: skip-chars-backward CHARACTER-SET &optional LIMIT
  397.      This function moves point backward, skipping characters that
  398.      match CHARACTER-SET.  It just like `skip-chars-forward' except
  399.      for the direction of motion.
  400.  
  401.  
  402. 
  403. File: elisp,  Node: Excursions,  Next: Narrowing,  Prev: Motion,  Up: Positions
  404.  
  405. Excursions
  406. ==========
  407.  
  408.    It is often useful to move point "temporarily" within a localized
  409. portion of the program, or to switch buffers temporarily.  This is
  410. called an "excursion", and it is done with the `save-excursion'
  411. special form.  This construct saves the current buffer and its values
  412. of point and the mark so they can be restored after the completion of
  413. the excursion.
  414.  
  415.    The forms for saving and restoring the configuration of windows
  416. are described elsewhere (*note Window Configurations::.).
  417.  
  418.  * Special Form: save-excursion FORMS...
  419.      The `save-excursion' special form saves the identity of the
  420.      current buffer and the values of point and the mark in it,
  421.      evaluates FORMS, and finally restores the buffer and its saved
  422.      values of point and the mark.  All three saved values are
  423.      restored even in case of an abnormal exit via throw or error
  424.      (*note Nonlocal Exits::.).
  425.  
  426.      The `save-excursion' special form is the standard way to switch
  427.      buffers or move point within one part of a program and avoid
  428.      affecting the rest of the program.  It is used more than 500
  429.      times in the Lisp sources of Emacs.
  430.  
  431.      The values of point and the mark for other buffers are not saved
  432.      by `save-excursion', so any changes made to point and the mark
  433.      in the other buffers will remain in effect after
  434.      `save-excursion' exits.
  435.  
  436.      Likewise, `save-excursion' does not restore window-buffer
  437.      correspondences altered by functions such as `switch-to-buffer'.
  438.      One way to restore these correspondences, and the selected
  439.      window, is to use `save-window-excursion' inside
  440.      `save-excursion' (*note Window Configurations::.).
  441.  
  442.      The value returned by `save-excursion' is the result of the last
  443.      of FORMS, or `nil' if no FORMS are given.
  444.  
  445.           (save-excursion
  446.             FORMS)
  447.           ==      
  448.           (let ((old-buf (current-buffer))
  449.                 (old-pnt (point-marker))
  450.                 (old-mark (copy-marker (mark-marker))))
  451.             (unwind-protect
  452.                 (progn FORMS)
  453.               (set-buffer old-buf)
  454.               (goto-char old-pnt)
  455.               (set-marker (mark-marker) old-mark)))
  456.  
  457.  
  458. 
  459. File: elisp,  Node: Narrowing,  Prev: Excursions,  Up: Positions
  460.  
  461. Narrowing
  462. =========
  463.  
  464.    "Narrowing" means limiting the text addressable by Emacs editing
  465. commands to a limited range of characters in a buffer.  The text that
  466. remains addressable is called the "accessible portion" of the buffer.
  467.  
  468.    Narrowing is specified with two buffer positions which become the
  469. beginning and end of the accessible portion.  For most editing
  470. commands these positions replace the values of the beginning and end
  471. of the buffer.  While narrowing is in effect, no text outside the
  472. accessible portion is displayed, and point cannot move outside the
  473. accessible portion.
  474.  
  475.    Values such as positions or line numbers which usually count from
  476. the beginning of the buffer continue to do so, but the functions
  477. which use them will refuse to operate on text that is inaccessible.
  478.  
  479.    The commands for saving buffers are unaffected by narrowing; the
  480. entire buffer is saved regardless of the any narrowing.
  481.  
  482.  * Command: narrow-to-region START END
  483.      This function sets the accessible portion of the current buffer
  484.      to start at START and end at END.  Both arguments should be
  485.      character positions.
  486.  
  487.      In an interactive call, START and END are set to the bounds of
  488.      the current region (point and the mark, with the smallest first).
  489.  
  490.  * Command: narrow-to-page MOVE-COUNT
  491.      This function sets the accessible portion of the current buffer
  492.      to include just the current page.  An optional first argument
  493.      MOVE-COUNT non-`nil' means to move forward or backward by
  494.      MOVE-COUNT pages and then narrow.
  495.  
  496.      In an interactive call, MOVE-COUNT is set to the numeric prefix
  497.      argument.
  498.  
  499.  * Command: widen
  500.      This function cancels any narrowing in the current buffer, so
  501.      that the entire contents are accessible.  This is called
  502.      "widening".  It is equivalent to the following expression:
  503.  
  504.           (narrow-to-region 1 (1+ (buffer-size)))
  505.  
  506.  * Special Form: save-restriction FORMS...
  507.      This special form saves the current bounds of the accessible
  508.      portion, evaluates FORMS, and finally restores the saved bounds,
  509.      thus restoring the same state of narrowing (or absence thereof)
  510.      formerly in effect.  The state of narrowing is restored even in
  511.      the event of an abnormal exit via throw or error (*note Nonlocal
  512.      Exits::.).  Therefore, this construct is a clean way to narrow a
  513.      buffer temporarily.
  514.  
  515.      The value returned by `save-restriction' is that returned by the
  516.      last of FORMS, or `nil' if no forms were given.
  517.  
  518.      *Note:* it is easy to make a mistake when using
  519.      `save-restriction'.  Read the entire description here before you
  520.      try it.
  521.  
  522.      Point and the mark are *not* restored by this special form; use
  523.      `save-excursion' for that.  If you use both `save-restriction'
  524.      and `save-excursion' together, `save-excursion' should come
  525.      first (on the outside).  Otherwise, the old point value would be
  526.      restored with temporary narrowing still in effect.  If the old
  527.      point value were outside the limits of the temporary narrowing,
  528.      this would fail to restore it accurately.
  529.  
  530.      The `save-restriction' special form records the values of the
  531.      beginning and end of the accessible portion as distances from
  532.      the beginning and end of the buffer.  In other words, it records
  533.      the amount of inaccessible text before and after the accessible
  534.      portion.
  535.  
  536.      This technique yields correct results if the body of the form
  537.      does further narrowing.  However, `save-restriction' can become
  538.      confused if the body widens and then makes changes outside the
  539.      area of the saved narrowing.  When this is what you want to do,
  540.      `save-restriction' is not the right tool for the job.  Here is
  541.      what you must do instead:
  542.  
  543.           (let ((beg (point-min-marker))
  544.                 (end (point-max-marker)))
  545.             (unwind-protect
  546.                 (progn BODY)
  547.               (narrow-to-region beg end)))
  548.  
  549.      Here is a simple example of correct use of `save-restriction':
  550.  
  551.           ---------- Buffer: foo ----------
  552.           This is the contents of foo
  553.           This is the contents of foo
  554.           This is the contents of foo-!-
  555.           ---------- Buffer: foo ----------
  556.           
  557.           (save-excursion
  558.             (save-restriction
  559.               (goto-char 1)
  560.               (forward-line 2)
  561.               (narrow-to-region 1 (point))
  562.               (goto-char (point-min))
  563.               (replace-string "foo" "bar")))
  564.           
  565.           ---------- Buffer: foo ----------
  566.           This is the contents of bar
  567.           This is the contents of bar
  568.           This is the contents of foo-!-
  569.           ---------- Buffer: foo ----------
  570.  
  571.  
  572. 
  573. File: elisp,  Node: Markers,  Next: Text,  Prev: Positions,  Up: Top
  574.  
  575. Markers
  576. *******
  577.  
  578.    A "marker" is a Lisp object used to specify a position in a buffer
  579. relative to the surrounding text.  A marker changes its offset from
  580. the beginning of the buffer automatically whenever text is inserted
  581. or deleted, so that it stays with the two characters on either side
  582. of it.
  583.  
  584. * Menu:
  585.  
  586. * Overview of Markers::      The components of a marker, and how it relocates.
  587. * Predicates on Markers::    Testing whether an object is a marker.
  588. * Creating Markers::         Making empty markers or markers at certain places.
  589. * Information from Markers:: Finding the marker's buffer or character position.
  590. * Changing Markers::         Moving the marker to a new buffer or position.
  591. * The Mark::                 How "the mark" is implemented with a marker.
  592. * The Region::               How to access "the region".
  593.  
  594.  
  595. 
  596. File: elisp,  Node: Overview of Markers,  Next: Predicates on Markers,  Prev: Markers,  Up: Markers
  597.  
  598. Overview of Markers
  599. ===================
  600.  
  601.    A marker specifies a buffer and a position in that buffer.  The
  602. marker can be used to represent a position in the functions that
  603. require one, just as an integer could be used.  *Note Positions::,
  604. for a complete description of positions.
  605.  
  606.    A marker has two attributes: the marker position, and the marker
  607. buffer.  The marker position is an integer which is equivalent (at
  608. the moment) to the marker as a position in that buffer; however, as
  609. text is inserted or deleted in the buffer, the marker is relocated,
  610. so that its integer equivalent changes.  The idea is that a marker
  611. positioned between two characters in a buffer will remain between
  612. those two characters despite any changes made to the contents of the
  613. buffer; thus, a marker's offset from the beginning of a buffer may
  614. change often during the life of the marker.
  615.  
  616.    If the text around a marker is deleted, the marker is repositioned
  617. between the characters immediately before and after the deleted text.
  618. If text is inserted at the position of a marker, the marker remains
  619. in front of the new text unless it is inserted with
  620. `insert-before-markers' (*note Insertion::.).  When text is inserted
  621. or deleted somewhere before the marker position (not next to the
  622. marker), the marker moves back and forth with the two neighboring
  623. characters.
  624.  
  625.    When a buffer is modified, all of its markers must be checked so
  626. that they can be relocated if necessary.  This slows processing in a
  627. buffer with a large number of markers.  For this reason, it is a good
  628. idea to make a marker point nowhere if you are sure you don't need it
  629. any more.  Unreferenced markers will eventually be garbage collected,
  630. but until then will continue to be updated if they do point somewhere.
  631.  
  632.    Because it is quite common to perform arithmetic operations on a
  633. marker position, most of the arithmetic operations (including `+' and
  634. `-') accept markers as arguments.  In such cases, the current
  635. position of the marker is used.
  636.  
  637.    Here are examples of creating markers, setting markers, and moving
  638. point to markers:
  639.  
  640.      ;; Make a new marker that initially does not point anywhere:
  641.      (setq m1 (make-marker))
  642.           => #<marker in no buffer>
  643.      
  644.      ;; Set `m1' to point between the 100th and 101st characters.
  645.      ;; in the current buffer:
  646.      (set-marker m1 100)
  647.           => #<marker at 100 in markers.texi>
  648.      
  649.      ;; Now insert one character at the beginning of the buffer:
  650.      (goto-char (point-min))
  651.           => 1
  652.      (insert "Q")
  653.           => nil
  654.      
  655.      ;; `m1' is updated appropriately.
  656.      m1
  657.           => #<marker at 101 in markers.texi>
  658.      
  659.      ;; Two markers that point to the same position
  660.      ;; are not `eq', but they are `equal'.
  661.      (setq m2 (copy-marker m1))
  662.           => #<marker at 101 in markers.texi>
  663.      (eq m1 m2)
  664.           => nil
  665.      (equal m1 m2)
  666.           => t
  667.      
  668.      ;; When you are finished using a marker, make it point nowhere.
  669.      (set-marker m1 nil)
  670.           => #<marker in no buffer>
  671.  
  672.  
  673. 
  674. File: elisp,  Node: Predicates on Markers,  Next: Creating Markers,  Prev: Overview of Markers,  Up: Markers
  675.  
  676. Predicates on Markers
  677. =====================
  678.  
  679.    You can test an object to see whether it is a marker, or whether
  680. it is either an integer or a marker.  The latter test is useful when
  681. you are using the arithmetic functions that work with both markers
  682. and integers.
  683.  
  684.  * Function: markerp OBJECT
  685.      This function returns `t' if OBJECT is a marker, `nil'
  686.      otherwise.  In particular, integers are not markers, even though
  687.      many functions will accept either a marker or an integer.
  688.  
  689.  * Function: integer-or-marker-p OBJECT
  690.      This function returns `t' if OBJECT is an integer or a marker,
  691.      `nil' otherwise.
  692.  
  693.  
  694. 
  695. File: elisp,  Node: Creating Markers,  Next: Information from Markers,  Prev: Predicates on Markers,  Up: Markers
  696.  
  697. Functions That Create Markers
  698. =============================
  699.  
  700.    When you create a new marker, you can make it point nowhere, or
  701. point to the present position of point, or to the beginning or end of
  702. the accessible portion of the buffer, or to the same place as another
  703. given marker.
  704.  
  705.  * Function: make-marker
  706.      This functions returns a newly allocated marker that does not
  707.      point anywhere.
  708.  
  709.           (make-marker)
  710.                => #<marker in no buffer>
  711.  
  712.  * Function: point-marker
  713.      This function returns a new marker that points to the present
  714.      position of point in the current buffer.  *Note Point::.  For an
  715.      example, see `copy-marker', below.
  716.  
  717.  * Function: point-min-marker
  718.      This function returns a new marker that points to the beginning
  719.      of the accessible portion of the buffer.  This will be the
  720.      beginning of the buffer unless narrowing is in effect.  *Note
  721.      Narrowing::.
  722.  
  723.  * Function: point-max-marker
  724.      This function returns a new marker that points to the end of the
  725.      accessible portion of the buffer.  This will be the end of the
  726.      buffer unless narrowing is in effect.  *Note Narrowing::.
  727.  
  728.      Here are examples of this function and `point-min-marker', shown
  729.      in a buffer containing a version of the source file for the text
  730.      of this chapter.
  731.  
  732.           (point-min-marker)
  733.                => #<marker at 1 in markers.texi>
  734.           (point-max-marker)
  735.                => #<marker at 15573 in markers.texi>
  736.           
  737.           (narrow-to-region 100 200)
  738.                => nil
  739.           (point-min-marker)
  740.                => #<marker at 100 in markers.texi>
  741.  
  742.              (point-max-marker)
  743.                => #<marker at 200 in markers.texi>
  744.  
  745.  * Function: copy-marker MARKER-OR-INTEGER
  746.      If passed a marker as its argument, `copy-marker' returns a new
  747.      marker that points to the same place and the same buffer as does
  748.      MARKER-OR-INTEGER.  If passed an integer as its argument,
  749.      `copy-marker' returns a new marker that points to position
  750.      MARKER-OR-INTEGER in the current buffer.
  751.  
  752.      If passed an argument that is an integer whose value is less
  753.      than 1, `copy-marker' returns a new marker that points to the
  754.      beginning of the current buffer.  If passed an argument that is
  755.      an integer whose value is greater than the length of the buffer,
  756.      then `copy-marker' returns a new marker that points to the end
  757.      of the buffer.
  758.  
  759.      An error is signaled if MARKER is neither a marker nor an integer.
  760.  
  761.           (setq p (point-marker))
  762.                => #<marker at 2139 in markers.texi>
  763.           
  764.           (setq q (copy-marker p))
  765.                => #<marker at 2139 in markers.texi>
  766.           
  767.           (eq p q)
  768.                => nil
  769.           
  770.           (equal p q)
  771.                => t
  772.           
  773.           (copy-marker 0)
  774.                => #<marker at 1 in markers.texi>
  775.           
  776.           (copy-marker 20000)
  777.                => #<marker at 7572 in markers.texi>
  778.  
  779.  
  780. 
  781. File: elisp,  Node: Information from Markers,  Next: Changing Markers,  Prev: Creating Markers,  Up: Markers
  782.  
  783. Information from Markers
  784. ========================
  785.  
  786.    This section describes the functions for accessing the components
  787. of a marker object.
  788.  
  789.  * Function: marker-position MARKER
  790.      This function returns the position that MARKER points to, or
  791.      `nil' if it points nowhere.
  792.  
  793.  * Function: marker-buffer MARKER
  794.      This function returns the buffer that MARKER points into, or
  795.      `nil' if it points nowhere.
  796.  
  797.           (setq m (make-marker))
  798.                => #<marker in no buffer>
  799.           (marker-position m)
  800.                => nil
  801.           (marker-buffer m)
  802.                => nil
  803.           
  804.           (set-marker m 3770 (current-buffer))
  805.                => #<marker at 3770 in markers.texi>
  806.           (marker-buffer m)
  807.                => #<buffer markers.texi>
  808.           (marker-position m)
  809.                => 3770
  810.  
  811.    Two distinct markers will be found `equal' (even though not `eq')
  812. to each other if they have the same position and buffer, or if they
  813. both point nowhere.
  814.  
  815.  
  816. 
  817. File: elisp,  Node: Changing Markers,  Next: The Mark,  Prev: Information from Markers,  Up: Markers
  818.  
  819. Changing Markers
  820. ================
  821.  
  822.    This section describes how to change the position of an existing
  823. marker.  When you do this, be sure you know whether the marker is
  824. used outside of your program, and, if so, what effects will result
  825. from moving it--otherwise, confusing things may happen in other parts
  826. of Emacs.
  827.  
  828.  * Function: set-marker MARKER POSITION &optional BUFFER
  829.      This function moves MARKER to POSITION in BUFFER.  If BUFFER is
  830.      not provided, it defaults to the current buffer.
  831.  
  832.      If POSITION is less than 1, `set-marker' moves marker to the
  833.      beginning of the buffer.  If the value of POSITION is greater
  834.      than the size of the buffer, `set-marker' moves marker to the
  835.      end of the buffer.  If POSITION is `nil' or a marker that points
  836.      nowhere, then MARKER is set to point nowhere.
  837.  
  838.      The value returned is MARKER.
  839.  
  840.           (setq m (point-marker))
  841.                => #<marker at 4714 in markers.texi>
  842.           (set-marker m 55)
  843.                => #<marker at 55 in markers.texi>
  844.           (setq b (get-buffer "foo"))
  845.                => #<buffer foo>
  846.           (set-marker m 0 b)
  847.                => #<marker at 1 in foo>
  848.  
  849.  * Function: move-marker MARKER POSITION &optional BUFFER
  850.      This is another name for `set-marker'.
  851.  
  852.  
  853. 
  854. File: elisp,  Node: The Mark,  Next: The Region,  Prev: Changing Markers,  Up: Markers
  855.  
  856. The Mark
  857. ========
  858.  
  859.    A special marker in each buffer is designated "the mark".  It
  860. records a position for the user for the sake of commands such as
  861. `C-w' and `C-x TAB'.  Lisp programs should set the mark only to
  862. values that have a potential use to the user, and never for their own
  863. internal purposes.  For example, the `replace-regexp' command sets
  864. the mark to the value of point before doing any replacements, because
  865. this enables the user to move back there conveniently after the
  866. replace is finished.
  867.  
  868.    Many commands are designed so that when called interactively they
  869. operate on the text between point and the mark.  If you are writing
  870. such a command, don't examine the mark directly; instead, use
  871. `interactive' with the `r' specification.  This will provide the
  872. values of point and the mark as arguments to the command in an
  873. interactive call, but will permit other Lisp programs to specify
  874. arguments explicitly.  *Note Interactive Codes::.
  875.  
  876.    Each buffer has its own value of the mark that is independent of
  877. the value of the mark in other buffers.  When a buffer is created,
  878. the mark exists but does not point anywhere.  We consider this state
  879. as "the absence of a mark in that buffer".
  880.  
  881.    In addition to the mark, each buffer has a "mark ring" which is a
  882. list of markers that are the previous values of the mark.  When
  883. editing commands change the mark, they should normally save the old
  884. value of the mark on the mark ring.  The mark ring may contain no
  885. more than the maximum number of entries specified by the variable
  886. `mark-ring-max'; excess entries are discarded on a first-in-first-out
  887. basis.
  888.  
  889.  * Function: mark
  890.      This function returns the position of the current buffer's mark
  891.      as an integer.  `nil' is returned if the mark is not yet set for
  892.      this buffer.
  893.  
  894.  * Function: mark-marker
  895.      This function returns the current buffer's mark.  This the very
  896.      marker which records the mark location inside Emacs, not a copy.
  897.      Therefore, changing this marker's position will directly affect
  898.      the position of the mark.  Don't do it unless that is the effect
  899.      you want.
  900.  
  901.           (setq m (mark-marker))
  902.                => #<marker at 3420 in markers.texi>
  903.           (set-marker m 100)
  904.                => #<marker at 100 in markers.texi>
  905.           (mark-marker)
  906.                => #<marker at 100 in markers.texi>
  907.  
  908.      Like any marker, this marker can be set to point at any buffer
  909.      you like.  We don't recommend that you make it point at any
  910.      buffer other than the one of which it is the mark.  If you do,
  911.      it will yield perfectly consistent, if rather odd, results.
  912.  
  913.  * Command: set-mark-command JUMP
  914.      If JUMP is `nil', this command sets the mark to the value of
  915.      point and pushes the previous value of the mark on the mark
  916.      ring.  The message `Mark set' is also displayed in the echo area.
  917.  
  918.      If JUMP is not `nil', this command sets point to the value of
  919.      the mark, and sets the mark to the previous saved mark value,
  920.      which is popped off the mark ring.
  921.  
  922.      This function is *only* intended for interactive use.
  923.  
  924.  * Function: set-mark POSITION
  925.      This function sets the mark to POSITION.  The old value of the
  926.      mark is *not* pushed onto the mark ring.
  927.  
  928.      *Note:* use this function only if you want the user to see that
  929.      the mark has moved, and you want the previous mark position to
  930.      be lost.  Normally, when a new mark is set, the old one should
  931.      go on the `mark-ring', which is why most applications should use
  932.      `push-mark' and `pop-mark', not `set-mark'.
  933.  
  934.      Novice Emacs Lisp programmers often try to use the mark for the
  935.      wrong purposes.  The mark saves a location for the user's
  936.      convenience.  An editing command should not alter the mark
  937.      unless altering the mark is part of the user-level functionality
  938.      of the command.  (And, in that case, this effect should be
  939.      documented.)  To remember a location for internal use in the
  940.      Lisp program, store it in a Lisp variable.  For example:
  941.  
  942.              (let ((beg (point)))
  943.                 (forward-line 1)
  944.                 (delete-region beg (point))).
  945.  
  946.   * Variable: mark-ring
  947.      The value of this buffer-local variable is the list of saved
  948.      former marks of the current buffer, most recent first.
  949.  
  950.           mark-ring
  951.           => (#<marker at 11050 in markers.texi> 
  952.               #<marker at 10832 in markers.texi>
  953.               ...)
  954.  
  955.  * User Option: mark-ring-max
  956.      The value of this variable is the maximum size of `mark-ring'. 
  957.      If more marks than this are pushed onto the `mark-ring', it
  958.      discards marks on a first-in, first-out basis.
  959.  
  960.  * Function: push-mark &optional POSITION NOMSG
  961.      This function sets the current buffer's mark to POSITION, and
  962.      pushes a copy of the previous mark onto `mark-ring'.  If
  963.      POSITION is `nil', then the value of point is used.  `push-mark'
  964.      returns `nil'.
  965.  
  966.      A `Mark set' message is displayed unless NOMSG is non-`nil'.
  967.  
  968.  * Function: pop-mark
  969.      This function pops off the top element of `mark-ring' and makes
  970.      that mark become the buffer's actual mark.  This does not change
  971.      the buffer's point and does nothing if `mark-ring' is empty.
  972.  
  973.      The return value is not useful.
  974.  
  975.  
  976. 
  977. File: elisp,  Node: The Region,  Prev: The Mark,  Up: Markers
  978.  
  979. The Region
  980. ==========
  981.  
  982.    The text between point and the mark is known as "the region". 
  983. Various functions operate on text delimited by point and the mark,
  984. but only those functions specifically related to the region itself
  985. are described here.
  986.  
  987.  * Function: region-beginning
  988.      This function returns the position of the beginning of the
  989.      region (as an integer).  This is the position of either point or
  990.      the mark, whichever is smaller.
  991.  
  992.      If the mark does not point anywhere, an error is signaled.
  993.  
  994.  * Function: region-end
  995.      This function returns the position of the end of the region (as
  996.      an integer).  This is the position of either point or the mark,
  997.      whichever is larger.
  998.  
  999.      If the mark does not point anywhere, an error is signaled.
  1000.  
  1001.    Few programs need to use the `region-beginning' and `region-end'
  1002. functions.  A command designed to operate on a region should instead
  1003. use `interactive' with the `r' specification, so that the same
  1004. function can be called with explicit bounds arguments from programs. 
  1005. (*Note Interactive Codes::.)
  1006.  
  1007.  
  1008. 
  1009. File: elisp,  Node: Text,  Next: Searching and Matching,  Prev: Markers,  Up: Top
  1010.  
  1011. Text
  1012. ****
  1013.  
  1014.    This chapter describes the functions that deal with the text in a
  1015. buffer.  Most examine, insert or delete text in the current buffer,
  1016. often in the vicinity of point.  Many are interactive.  All the
  1017. functions that change the text provide for undoing the changes (*note
  1018. Undo::.).
  1019.  
  1020.    Many text-related functions operate on a region of text defined by
  1021. two buffer positions passed in arguments named START and END.  These
  1022. arguments should be either markers (*note Markers::.) or or numeric
  1023. character positions (*note Positions::.).  The order of these
  1024. arguments does not matter; it is all right for START to be the end of
  1025. the region and END the beginning.  For example, `(delete-region 1
  1026. 10)' and `(delete-region 10 1)' perform identically.  An
  1027. `args-out-of-range' error is signaled if either START or END is
  1028. outside the accessible portion of the buffer.  In an interactive
  1029. call, point and the mark are used for these arguments.
  1030.  
  1031.    Throughout this chapter, "text" refers to the characters in the
  1032. buffer.
  1033.  
  1034. * Menu:
  1035.  
  1036. * Near Point::       Examining text in the vicinity of point.
  1037. * Buffer Contents::  Examining text in a general fashion.
  1038. * Insertion::        Adding new text to a buffer.
  1039. * Commands for Insertion::  User-level commands to insert text.
  1040. * Deletion::         Removing text from a buffer.
  1041. * User-Level Deletion::     User-level commands to delete text.
  1042. * The Kill Ring::    Where removed text sometimes is saved for later use.
  1043. * Undo::             Undoing changes to the text of a buffer.
  1044. * Auto Filling::     How auto-fill mode is implemented to break lines.
  1045. * Filling::          Functions for explicit filling.
  1046. * Sorting::          Functions for sorting parts of the buffer.
  1047. * Indentation::      Functions to insert or adjust indentation.
  1048. * Columns::          Computing horizontal positions, and using them.
  1049. * Case Changes::     Case conversion of parts of the buffer.
  1050. * Substitution::     Replacing a given character wherever it appears.
  1051. * Underlining::      Inserting or deleting underlining-by-overstrike.
  1052. * Registers::        How registers are implemented.  Accessing the text or
  1053.                        position stored in a register.
  1054.  
  1055.  
  1056. 
  1057. File: elisp,  Node: Near Point,  Next: Buffer Contents,  Prev: Text,  Up: Text
  1058.  
  1059. Examining Text Near Point
  1060. =========================
  1061.  
  1062.    Many functions are provided to look at the characters around point.
  1063. Several simple functions are described here.  See also `looking-at'
  1064. in *Note Searching and Matching::.
  1065.  
  1066.  * Function: char-after POSITION
  1067.      This function returns the character in the current buffer at
  1068.      (i.e., immediately after) position POSITION.  If POSITION is out
  1069.      of range for this purpose, either before the beginning of the
  1070.      buffer, or at or beyond the end, than the value is `nil'.
  1071.  
  1072.      Remember that point is always between characters, and the
  1073.      terminal cursor normally appears over the character following
  1074.      point.  Therefore, the character returned by `char-after' is the
  1075.      character the cursor is over.
  1076.  
  1077.      In the following example, assume that the first character in the
  1078.      buffer is `@':
  1079.  
  1080.           (char-to-string (char-after 1))
  1081.                => "@"
  1082.  
  1083.  * Function: following-char
  1084.      This function returns the character following point in the
  1085.      current buffer.  This is similar to `(char-after (point))'. 
  1086.      However, point is at the end of the buffer, then the result of
  1087.      `following-char' is 0.
  1088.  
  1089.      In this example, point is between the `a' and the `c'.
  1090.  
  1091.           ---------- Buffer: foo ----------
  1092.           Gentlemen may cry ``Pea-!-ce! Peace!,'' but there is no peace.
  1093.           ---------- Buffer: foo ----------
  1094.           
  1095.           (char-to-string (preceding-char))
  1096.                => "a"
  1097.           (char-to-string (following-char))
  1098.                => "c"
  1099.  
  1100.  * Function: preceding-char
  1101.      This function returns the character preceding point in the
  1102.      current buffer.  See above, under `following-char', for an
  1103.      example.  If point is at the beginning of the buffer, then the
  1104.      result of `preceding-char' is 0.
  1105.  
  1106.  * Function: bobp
  1107.      This function returns `t' if point is at the beginning of the
  1108.      buffer.  If narrowing is in effect, this means the beginning of
  1109.      the accessible portion of the text.  See also `point-min' in
  1110.      *Note Point::.
  1111.  
  1112.  * Function: eobp
  1113.      This function returns `t' if point is at the end of the buffer. 
  1114.      If narrowing is in effect, this means the end of accessible
  1115.      portion of the text.  See also `point-max' in *Note Point::.
  1116.  
  1117.  * Function: bolp
  1118.      This function returns `t' if point is at the beginning of a line.
  1119.      *Note Text Lines::.
  1120.  
  1121.  * Function: eolp
  1122.      This function returns `t' if point is at the end of a line.  The
  1123.      end of the buffer is always considered the end of a line.
  1124.  
  1125.  
  1126. 
  1127. File: elisp,  Node: Buffer Contents,  Next: Insertion,  Prev: Near Point,  Up: Text
  1128.  
  1129. Examining Buffer Contents
  1130. =========================
  1131.  
  1132.    This section describes two functions that allow a Lisp program to
  1133. convert any portion of the text in the buffer into a string.
  1134.  
  1135.  * Function: buffer-substring START END
  1136.      This function returns a string containing a copy of the text of
  1137.      the region defined by positions START and END in the current
  1138.      buffer.  If the arguments are not positions in the accessible
  1139.      portion of the buffer, Emacs signals an `args-out-of-range' error.
  1140.  
  1141.      It is not necessary for START to be less than END; the arguments
  1142.      can be given in either order.  But most often the smaller
  1143.      argument is written first.
  1144.  
  1145.           ---------- Buffer: foo ----------
  1146.           This is the contents of buffer foo
  1147.           
  1148.           ---------- Buffer: foo ----------
  1149.           
  1150.           (buffer-substring 1 10)
  1151.           => "This is t"
  1152.           (buffer-substring (point-max) 10)
  1153.           => "he contents of buffer foo
  1154.           "
  1155.  
  1156.  * Function: buffer-string
  1157.      This function returns the contents of the accessible portion of
  1158.      the current buffer as a string.  This is the portion between
  1159.      `(point-min)' and `(point-max)' (*note Narrowing::.).
  1160.  
  1161.           ---------- Buffer: foo ----------
  1162.           This is the contents of buffer foo
  1163.           
  1164.           ---------- Buffer: foo ----------
  1165.           
  1166.           (buffer-string)
  1167.                => "This is the contents of buffer foo
  1168.           "
  1169.  
  1170.  
  1171. 
  1172. File: elisp,  Node: Insertion,  Next: Commands for Insertion,  Prev: Buffer Contents,  Up: Text
  1173.  
  1174. Insertion
  1175. =========
  1176.  
  1177.    Insertion takes place at point.  Markers pointing at positions
  1178. after the insertion point are relocated with the surrounding text
  1179. (*note Markers::.).  When a marker points at the place of insertion,
  1180. it is normally not relocated, so that it points to the beginning of
  1181. the inserted text; however, when `insert-before-markers' is used, all
  1182. such markers are relocated to point after the inserted text.
  1183.  
  1184.    Point may end up either before or after inserted text, depending
  1185. on the function used.  If point is left after the inserted text, we
  1186. speak of insertion "before point".
  1187.  
  1188.    Each of these functions signals an error if the current buffer is
  1189. read-only.
  1190.  
  1191.  * Function: insert &rest ARGS
  1192.      This function inserts the strings and/or characters ARGS into
  1193.      the current buffer, at point, moving point forward.  An error is
  1194.      signaled unless all ARGS are either strings or characters.  The
  1195.      value is `nil'.
  1196.  
  1197.  * Function: insert-before-markers &rest ARGS
  1198.      This function inserts the strings and/or characters ARGS into
  1199.      the current buffer, at point, moving point forward.  An error is
  1200.      signaled unless all ARGS are either strings or characters.  The
  1201.      value is `nil'.
  1202.  
  1203.      This function is unlike the other insertion functions in that a
  1204.      marker whose position initially equals point is relocated to
  1205.      come after the newly inserted text.
  1206.  
  1207.  * Function: insert-char CHARACTER COUNT
  1208.      This function inserts COUNT instances of CHARACTER into the
  1209.      current buffer before point.  COUNT must be a number, and
  1210.      CHARACTER must be a character.  The value is `nil'.
  1211.  
  1212.  * Function: insert-buffer-substring FROM-BUFFER-OR-NAME START END
  1213.      This function inserts a substring of the contents of buffer
  1214.      FROM-BUFFER-OR-NAME (which must already exist) into the current
  1215.      buffer before point.  The text inserted consists of the
  1216.      characters in the region defined by START and END.  The value is
  1217.      `nil'.
  1218.  
  1219.      In this example, the form is executed with buffer `bar' as the
  1220.      current buffer.  We assume that buffer `bar' is initially empty.
  1221.  
  1222.           ---------- Buffer: foo ----------
  1223.           We hold these truths to be self-evident, that all
  1224.           ---------- Buffer: foo ----------
  1225.           
  1226.           (insert-buffer-substring "foo" 1 20)
  1227.                => nil
  1228.           
  1229.           ---------- Buffer: bar ----------
  1230.           We hold these truth
  1231.           ---------- Buffer: bar ----------
  1232.  
  1233.  
  1234.